Skip to content

fix(js): resume interrupted creates when the metadata PDA holds a pre-allocated buffer - #129

Merged
lorisleiva merged 5 commits into
solana-program:mainfrom
xeroc:fix/resume-interrupted-metadata-create
Nov 10, 2026
Merged

lorisleiva merged 5 commits into
solana-program:mainfrom
xeroc:fix/resume-interrupted-metadata-create

Conversation

@xeroc

@xeroc xeroc commented Oct 30, 2026

Copy link
Copy Markdown
Contributor

Fixes #128

Problem

getWriteMetadataInstructionPlan chose between the create and update flows solely on whether an account exists at the metadata PDA. A create interrupted between the buffer writes and the initialize instruction leaves a pre-allocated buffer (discriminator Buffer) at that PDA; the generated metadata decoder accepts it as an existing metadata account, so every subsequent write took the update flow. The update flow plans a fresh keypair buffer, a full set of chunk writes and a final set_data — which fails on-chain with Instruction requires an initialized account after the buffer transactions have already been sent, leaking a rent-exempt buffer on every retry.

Change

getWriteMetadataInstructionPlan now routes on the account discriminator:

  • absent account → create (unchanged),
  • initialized metadata account → update (unchanged),
  • pre-allocated buffer → new getResumeMetadataInstructionPlan:
    • data already present → a single initialize instruction resumes the create,
    • different data → rent transfer + extend plan, then a full rewrite before initialize,
    • data smaller than the buffer → rejected with close-buffer guidance, since buffer accounts cannot shrink and initialize derives data_length from the account size,
  • any other discriminator → explicit error.

Testing

Four new integration tests in clients/js/test/writeMetadata.test.ts construct the stuck PDA in LiteSVM (pre-allocated buffer + chunk writes, no initialize) and cover: resume with identical data, rewrite of same-length stale data, extend for larger data, and the rejection of smaller data. The identical-data scenario reproduced the exact production failure (Instruction requires an initialized account) before the fix. Full suite: 128 passed; oxlint, oxfmt and tsc clean.

Also verified against the mainnet incident that motivated this: the resume path's single-initialize transaction was executed manually to complete a stuck 13 KB IDL upload, after which the standard write command succeeded again.

Comment thread clients/js/src/createMetadata.ts Resolved
@mcintyre94

Copy link
Copy Markdown
Member

@trevor-cortex

@trevor-cortex trevor-cortex left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Summary

getWriteMetadataInstructionPlan now dispatches on the account discriminator instead of mere existence. A Buffer-discriminated account at the metadata PDA (a create interrupted before initialize) is routed to a new getResumeMetadataInstructionPlan, which emits a lone initialize when the buffer already holds the desired bytes, or grows + rewrites first when it doesn't. Smaller data is rejected with close-buffer guidance; unknown discriminators throw. Four LiteSVM tests build the stuck PDA by hand and cover the identical / same-length / larger / smaller cases.

I checked the approach against the program and it holds up:

  • Buffer and Metadata headers are both 96 bytes (the Rust Buffer struct carries explicit padding for exactly this), so decoding the stuck PDA with the metadata decoder gives a correct data slice.
  • initialize on a Buffer-discriminated PDA derives data_length from data_len() - Header::LEN, and trim on a buffer only reclaims excess lamports without resizing, so the "cannot shrink, close it" rejection is accurate.
  • allocate stores the signer as the buffer authority, so close-buffer <pda> succeeds through the explicit-authority path even for canonical buffers (the CLI command doesn't pass program/programData).

Things to look at

  1. Self-referential buffer footgun (inline at L125). If a caller passes the stuck PDA itself as input.buffer — plausible after seeing it in list-buffers — dataEquals is trivially true, the plan emits initialize, then close on the just-initialized metadata account. For non-canonical metadata the close succeeds (authority is stored on the header), destroying the account; for canonical it fails with IncorrectAuthority. A one-line guard fixes it.
  2. Rent top-up over-funds by the 128-byte header (inline at L144). getMinimumBalance(growth) adds the account header by default; getExtraRent in updateMetadata.ts passes { withoutHeader: true } for the same situation. Not a correctness issue, just ~0.0009 SOL stranded per extend.
  3. Source precedence differs from create/update (inline at L125). Those flows prefer buffer over data; this one prefers data.

Notes for other reviewers

  • The writeMetadata docblock (unchanged, ~L36–44 of writeMetadata.ts) still says "if so, the operation is an update, otherwise it is a create" — worth a one-liner about the resume path since that's where a reader would look first.
  • Tests only exercise the canonical PDA with data as the source. A non-canonical case and a --buffer-as-source case would be cheap additions, though I don't think they're blocking.
  • No .changeset/ in this repo, so nothing needed on that front despite the new public export.

Comment thread clients/js/src/createMetadata.ts Resolved
Comment thread clients/js/src/createMetadata.ts Resolved
Comment thread clients/js/src/createMetadata.ts Resolved
@xeroc

xeroc commented Oct 30, 2026

Copy link
Copy Markdown
Contributor Author

Thank you for the review. Commit 691a18e has all the changes.

bytesEqual — Done. The local dataEquals helper is gone. The code now uses bytesEqual from Kit.

Guard when buffer is the metadata PDA — Our decision: the function throws an error before it builds the plan. The new error is: `buffer` must not be the metadata account itself. The write instruction rejects source == target, so this input has no correct use. An error is safer than a fallback to data, because a fallback can hide the problem in your input.

Rent for the extend transfer — The transfer now uses getMinimumBalance(growth, { withoutHeader: true }). We did not export getExtraRent, because this plan has only one call site. The code in updateBuffer.ts uses the same expression without a helper.

Precedence of buffer and data — The resume plan now uses input.buffer?.data.data ?? input.data, so it aligns with the create and update flows. When you give a buffer and data, the rewrite is one write instruction with sourceBuffer, not chunk writes.

Close and re-create for small data — We keep the error. We do not know that the runtime accepts a close and a re-create of one account in the same transaction. The error tells you how to correct this: close the buffer with close-buffer, then try again. We can add the self-healing path in a new PR after we do more tests.

Other changes — The writeMetadata documentation now tells the reader about the resume path. Three new tests cover the guard, the buffer source when data is different, and the non-canonical PDA.

Tool output: vitest — 131 passed. oxlint, oxfmt, tsc — no problems.

@lorisleiva

Copy link
Copy Markdown
Member

Hey 👋 Thanks for the fix! I pushed a commit on top to save us some back and forth. Instead of a separate resume helper, the create factories now check the metadata PDA's state and skip whatever an interrupted create already did. That means create gets fixed as well as write. I also made update fail early on a pre-allocated buffer, and switched to fetching the metadata and buffer accounts in a single getMultipleAccounts call. The buried error.cause.cause was a Kit bug, fixed in anza-xyz/kit#2165. Lmk what you think 🙂

@lorisleiva
lorisleiva requested review from trevor-cortex and a balanced review from Copilot and removed request for Copilot November 2, 2026 15:21

@trevor-cortex trevor-cortex left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Re-review

Significant rework since my first pass. The resume logic no longer lives in a separate getResumeMetadataInstructionPlan; instead the create flow itself became resumable: getCreateMetadataInstructionPlan accepts the fetched PDA account (CreateMetadataTarget), getMetadataPdaState reduces it to { address, allocated, data, lamports }, and the new shared getCreateMetadataInstructionPlanUsingPdaBuffer skips whichever steps already landed (rent, allocate, extend, write). writeMetadata just routes on isInitializedMetadata, updateMetadata refuses buffers up front, and the CLI commands batch the PDA + source-buffer fetch into one getMultipleAccounts call and warn when resuming.

All points from my previous review are addressed:

  • self-referential buffer now throws (buffer must not be the metadata account itself), with a test;
  • rent top-up is now requiredRent - pda.lamports, which is strictly better than my withoutHeader suggestion — verified with the "only transfers the missing rent" test;
  • buffer takes precedence over data, matching create/update, with a test;
  • writeMetadata docblock updated;
  • non-canonical and --buffer-as-source cases covered.

I re-checked the on-chain assumptions against the new shape: both generated decoders read data as the remainder after the 96-byte header (getBytesDecoder(), not sliced by dataLength), so pda.data is correct whether the PDA was decoded via decodeBuffer or decodeMetadata; write resizes to max(len, offset + data.len) so it grows but never shrinks; extend accepts a Buffer-discriminated account through validate_authority. The growth computation reproduces the old needsExtend semantics for the fresh-allocate path and only counts the remaining bytes once allocated, so the singleExtendPerTransaction / CPI budget remains right.

Two non-blocking nits inline (funded-but-unallocated PDA re-transfers the full rent; the existing-buffer path could skip the write when the PDA already holds the source bytes), plus one consistency note on updateMetadata. None of these need to hold the merge.

Notes for other reviewers

  • getDecodedAccountDiscriminator duck-types on data + lamports + data.discriminator. That's fine for the inputs CreateMetadataTarget admits today (addresses, HasAddress, signers, decoded accounts), but it's the kind of helper that silently misroutes if someone later passes a custom object with those keys. Worth keeping in mind if the input union grows.
  • getMetadataPdaState is called twice on the input.buffer path (once in getCreateMetadataInstructionPlan, once in …UsingExistingBuffer). Pure and cheap, so not an issue, just noting it's intentional rather than a leftover.
  • The CLI still does its own fetchEncodedAccount in getCanonicalPdaDetailsUnchecked, so the "single RPC request" guarantee in the test applies to the library entry points, not the CLI end-to-end.

Comment thread clients/js/src/createMetadata.ts Resolved
Comment thread clients/js/src/createMetadata.ts Resolved
Comment thread clients/js/src/updateMetadata.ts Resolved

@trevor-cortex trevor-cortex left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Re-review (3rd pass)

Only updateMetadata.ts, internals.ts and updateMetadata.test.ts moved since my last review; createMetadata.ts is unchanged. The delta addresses the consistency note I left last time: updateMetadata now goes through the same fetchMetadataAndBuffer + decodeMaybeMetadataOrBuffer path as create/write, so foreign-owned accounts and unknown discriminators are rejected before any planning, and a funded-but-empty PDA is reported as missing (surfacing as SOLANA_ERROR__ACCOUNTS__ACCOUNT_NOT_FOUND, same as before via fetchMetadata). The three new tests cover exactly those branches — pre-allocated buffer (with the payer balance check proving nothing was sent), foreign owner, and missing account.

Nothing new to flag. The two remaining nits from my previous review (full-rent re-transfer on a funded-but-unallocated PDA, and skipping the write on the existing-buffer path when bytes already match) are still open but were explicitly non-blocking. Still approved.

@lorisleiva
lorisleiva requested a review from mcintyre94 November 2, 2026 15:55
@xeroc

xeroc commented Nov 6, 2026

Copy link
Copy Markdown
Contributor Author

@lorisleiva Thank you for the rework! We read it in full and we like it. One create flow that resumes itself is the correct design. The requiredRent - pda.lamports rent math is also better than our withoutHeader fix, because it covers buffers with partial funds. The early checks in update are a good change too.

@trevor-cortex Both of your open points are now addressed in cd2c642. We prefer simple code, and both points were non-blocking, so this commit is optional. Remove it if you like the code better without it. We decided to do the work anyway, because each fix is small:

  • A funded but empty PDA lost its lamports in decodeMaybeMetadataOrBuffer, so the create flow transferred the full rent again. The decoder now reports those lamports, and both create paths transfer only the rent that is missing.
  • The buffer path always copied the source bytes, even when the PDA already held them. It now skips the write instruction, as the data path does.

Two new tests cover both cases. The full suite passes: 148 tests.

@mcintyre94 Your bytesEqual point is done since 691a18e. Please review again when you have time. Your approval is the last open item before the merge.

@mcintyre94 mcintyre94 left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM! Let me take a look at the audit CI job and then we can get this merged, thankyou!

@lorisleiva

Copy link
Copy Markdown
Member

@xeroc would you mind rebasing this PR to make CI pass? Then let's get this merged. 🚀

xeroc and others added 5 commits November 10, 2026 09:15
…-allocated buffer

The write flow decided between create and update solely on whether an
account exists at the metadata PDA. A create that is interrupted between
the buffer writes and the initialize instruction leaves a pre-allocated
buffer (discriminator: Buffer) at that PDA, which decoded as an existing
metadata account and routed every subsequent write into the update flow.
The update flow then planned a fresh keypair buffer, a full set of chunk
writes and a final set_data that fails on-chain with 'instruction
requires an initialized account' — after the buffer transactions had
already been sent, leaking rent-exempt buffers on every retry.

Route on the account discriminator instead:

- absent account -> create (unchanged)
- initialized metadata account -> update (unchanged)
- pre-allocated buffer -> resume: initialize the account in place,
  rewriting the data (and growing the buffer) when it differs, and
  rejecting data smaller than the buffer since buffer accounts cannot
  shrink
- Reject `buffer` == metadata PDA with an explicit error instead of
  initializing the account only to close it right after
- Prefer `buffer` over `data`, matching the create and update flows
- Fund extends with `withoutHeader: true` so the existing account
  header is not paid for twice (~0.0009 SOL stranded per extend)
- Use Kit's `bytesEqual` instead of the local `dataEquals` helper
- Document the resume path in `writeMetadata`'s docblock

New tests: buffer==PDA guard throws, source buffer preferred over
conflicting inline data, non-canonical PDA resume. Suite: 131 passed;
oxlint, oxffmt and tsc clean.
Fold the resume logic into the buffer-based create factories, which now
inspect the state of the metadata PDA and skip the steps an interrupted
create already completed (rent, allocate, extend, write). Callers pass the
fetched account straight through, so `createMetadata`, `writeMetadata` and
the CLI no longer duplicate the "already exists" check.

Reject updates on a pre-allocated buffer before sending any transaction,
and fetch the metadata and source buffer accounts using a single
`getMultipleAccounts` request.
…rites

- Carry the lamports of a funded, empty metadata PDA through
  `decodeMaybeMetadataOrBuffer` so the create flow transfers only the
  rent that is missing
- Accept `existingLamports` in the instruction-data plan, which had the
  same full-rent transfer
- Skip the source-buffer `write` when the PDA already holds its bytes,
  mirroring the data path's `bytesEqual` short-circuit

Optional polish from the review round; plan shapes stay compatible.
Tests: pre-funded PDA keeps its exact balance, buffer-source resume
plans a single `initialize`. Suite: 148 passed.
@xeroc
xeroc force-pushed the fix/resume-interrupted-metadata-create branch from cd2c642 to 0dd5326 Compare November 10, 2026 08:17
@xeroc

xeroc commented Nov 10, 2026

Copy link
Copy Markdown
Contributor Author

The rebase on main is done and pushed (0dd5326). The CI workflow for the new head now waits with the status "action required", because the push comes from a fork without write access. One of the admins must approve the run in the Actions tab ("Approve and run") so that CI starts. @lorisleiva or @mcintyre94, can you click it? Then we can merge.

@lorisleiva

Copy link
Copy Markdown
Member

Thanks! Just gonna trigger one last AI review to make sure nothing got lost on the rebase whilst we wait for CI. ☺️

@trevor-cortex trevor-cortex left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Re-review (4th pass)

Changes since my last approval are confined to createMetadata.ts, createMetadata.test.ts, a new extendInstructionPlan.test.ts, and a one-line tweak in internals.ts. From the diff these address the two non-blocking nits I had left open plus xeroc's comments:

  • Funded-but-unallocated PDA no longer re-transfers the full rent. decodeMaybeMetadataOrBuffer now carries lamports through on its synthetic missing account, and getMetadataPdaState reads it on the exists: false branch, so missingRent is correct for a PDA that only got the system transfer before the create was interrupted. The docblock claim I flagged as overclaiming is now accurate.
  • Existing-buffer path short-circuits the write when the PDA already holds the source bytes. getCreateMetadataInstructionPlanUsingExistingBuffer now applies the same bytesEqual check as the inline-data path, so a --buffer retry on a fully-written PDA emits only initialize (+ optional close). Symmetric with the data path, and covered by the new test.
  • extendInstructionPlan covers the allocated + partially extended case. The new test pins down that growth is computed from the remaining bytes, not the full target, so the single-extend-per-transaction CPI budget isn't blown by a resume. Good to have this isolated rather than only implicitly exercised through writeMetadata.

I re-read the final createMetadata.ts end to end against the program's allocate / extend / write / initialize processors; the resume branches still line up (grow-never-shrink on write, extend accepted on Buffer-discriminated PDAs, initialize sizing from account length). No new issues.

All my earlier points are now resolved. Approving; nothing from me is holding the merge once Callum's audit CI check clears.

@trevor-cortex

Copy link
Copy Markdown

Small correction to my review above: the new test in extendInstructionPlan.test.ts is the "skips the write when the pre-allocated buffer already holds the source data" case (the --buffer short-circuit), not an extend-growth test. The resume-with-extend scenario is covered end-to-end by "extends a pre-allocated buffer by more than the realloc limit when resuming an interrupted create" in createMetadata.test.ts. The growth math itself is unchanged since my last pass, so nothing else changes — approval stands.

@lorisleiva
lorisleiva merged commit 7cbd414 into solana-program:main Nov 10, 2026
22 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

write: interrupted create leaves the metadata PDA as a pre-allocated buffer; every retry fails at set_data and leaks a rent-exempt buffer

4 participants